Authoring dynamic scientific documents with Quarto
Marie-Hélène Burle
April 11, 2023
Markup languages control the formatting of text documents. They are powerful but complex and the raw text (before it is rendered into its formatted version) is visually cluttered and hard to read.
Examples of markup languages include LaTeX and HTML.
Tex is often used with the macro package LaTeX.
Example LaTeX:
HTML is often used with css or scss files to customize the format.
Example HTML:
<!DOCTYPE html>
<html lang="en-US">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width" />
<title>My title</title>
<address class="author">My name</address>
<input type="date" value="2022-11-24" />
</head>
<h1>First section</h1>
<body>
Some text in the first section.
</body>
</html>A number of minimalist markup languages intend to remove all the visual clutter and complexity to create raw texts that are readable prior to rendering. Markdown (note the pun with “markup”), created in 2004, is the most popular of them. Due to its simplicity, it has become quasi-ubiquitous. Many implementations exist which add a varying number of features (as you can imagine, a very simple markup language is also fairly limited).
Markdown files are simply text files and they use the .md extension.
In its basic form, Markdown is mostly used to create webpages. Conveniently, raw HTML can be included whenever the limited markdown syntax isn’t sufficient.
Here is an overview of the Markdown syntax supported by many applications.
While the basic syntax is good enough for HTML outputs, it is very limited for other formats.
Pandoc is a free and open-source markup format converter. Pandoc supports an extended Markdown syntax with functionality for figures, tables, callout blocks, LaTeX mathematical equations, citations, and YAML metadata blocks. In short, everything needed for the creation of scientific documents.
Such documents remain as readable as basic Markdown documents (thus respecting the Markdown philosophy), but they can now be rendered in sophisticated pdf, books, entire websites, Word documents, etc.
And of course, as such documents remain text files, you can put them under version control with Git.
Previous example using Pandoc’s Markdown:
Literate programming is a methodology that combines snippets of code and written text. While first introduced in 1984, this approach to the creation of documents has truly exploded in popularity in recent years thanks to the development of new tools such as R Markdown and, later, Jupyter notebooks.
Quarto files are turned into Markdown by Jupyter (for Python or Julia) or knitr (for R), then pandoc turns the Markdown document into the output of your choice.
From Quarto documentation
From Quarto documentation
Quarto files use the extension .qmd.
You can use Quarto directly from RStudio or a Jupyter notebook.
From Quarto documentation
In this webinar, I will simply use a text editor.
Syntax highlighting in pretty much any language.
Executable code blocks in:
- HTML
- PDF
- MS Word
- OpenOffice
- ePub
- Revealjs
- PowerPoint
- Beamer
- GitHub Markdown
- CommonMark
- Hugo
- Docusaurus
- Markua
- MediaWiki
- DokuWiki
- ZimWiki
- Jira Wiki
- XWiki
- JATS
- Jupyter
- ConTeXt
- RTF
- reST
- AsciiDoc
- Org-Mode
- Muse
- GNU
- Groff
This training website is actually built with Quarto!
Written in YAML. Sets the options for the document. Let’s see a few examples.
HTML output:
HTML output with a few options:
MS Word output with Python code blocks:
revealjs output with some options and Julia code blocks:
---
title: "Some title"
subtitle: "Some subtitle"
institute: "Simon Fraser University"
date: "2022-11-24"
execute:
error: true
echo: true
format:
revealjs:
theme: [default, custom.scss]
highlight-style: monokai
code-line-numbers: false
embed-resources: true
jupyter: julia-1.8
---See the Quarto documentation for an exhaustive list of options for all formats.
Written sections are written in Pandoc’s extended Markdown.
If all you want is syntax highlighting of the code blocks, use this syntax:
{{.language}} <some code>
If you want syntax highlighting of the blocks and for the code to run, use instead:
In addition, options can be added to individual code blocks:
There are only two commands you need to know.
In a terminal, simply run either of:
You can find several examples in our previous workshop on Quarto